1   /*
2    * Copyright 2002-2012 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.jdbc.support.lob;
18  
19  import java.io.Closeable;
20  import java.io.InputStream;
21  import java.io.Reader;
22  import java.sql.PreparedStatement;
23  import java.sql.SQLException;
24  
25  /**
26   * Interface that abstracts potentially database-specific creation of large binary
27   * fields and large text fields. Does not work with {@code java.sql.Blob}
28   * and {@code java.sql.Clob} instances in the API, as some JDBC drivers
29   * do not support these types as such.
30   *
31   * <p>The LOB creation part is where {@link LobHandler} implementations usually
32   * differ. Possible strategies include usage of
33   * {@code PreparedStatement.setBinaryStream/setCharacterStream} but also
34   * {@code PreparedStatement.setBlob/setClob} with either a stream argument
35   * (requires JDBC 4.0) or {@code java.sql.Blob/Clob} wrapper objects.
36   *
37   * <p>A LobCreator represents a session for creating BLOBs: It is <i>not</i>
38   * thread-safe and needs to be instantiated for each statement execution or for
39   * each transaction. Each LobCreator needs to be closed after completion.
40   *
41   * <p>For convenient working with a PreparedStatement and a LobCreator,
42   * consider using {@link org.springframework.jdbc.core.JdbcTemplate} with an
43   *{@link org.springframework.jdbc.core.support.AbstractLobCreatingPreparedStatementCallback}
44   * implementation. See the latter's javadoc for details.
45   *
46   * @author Juergen Hoeller
47   * @since 04.12.2003
48   * @see #close()
49   * @see LobHandler#getLobCreator()
50   * @see DefaultLobHandler.DefaultLobCreator
51   * @see OracleLobHandler.OracleLobCreator
52   * @see java.sql.PreparedStatement#setBlob
53   * @see java.sql.PreparedStatement#setClob
54   * @see java.sql.PreparedStatement#setBytes
55   * @see java.sql.PreparedStatement#setBinaryStream
56   * @see java.sql.PreparedStatement#setString
57   * @see java.sql.PreparedStatement#setAsciiStream
58   * @see java.sql.PreparedStatement#setCharacterStream
59   */
60  public interface LobCreator extends Closeable {
61  
62  	/**
63  	 * Set the given content as bytes on the given statement, using the given
64  	 * parameter index. Might simply invoke {@code PreparedStatement.setBytes}
65  	 * or create a Blob instance for it, depending on the database and driver.
66  	 * @param ps the PreparedStatement to the set the content on
67  	 * @param paramIndex the parameter index to use
68  	 * @param content the content as byte array, or {@code null} for SQL NULL
69  	 * @throws SQLException if thrown by JDBC methods
70  	 * @see java.sql.PreparedStatement#setBytes
71  	 */
72  	void setBlobAsBytes(PreparedStatement ps, int paramIndex, byte[] content)
73  			throws SQLException;
74  
75  	/**
76  	 * Set the given content as binary stream on the given statement, using the given
77  	 * parameter index. Might simply invoke {@code PreparedStatement.setBinaryStream}
78  	 * or create a Blob instance for it, depending on the database and driver.
79  	 * @param ps the PreparedStatement to the set the content on
80  	 * @param paramIndex the parameter index to use
81  	 * @param contentStream the content as binary stream, or {@code null} for SQL NULL
82  	 * @throws SQLException if thrown by JDBC methods
83  	 * @see java.sql.PreparedStatement#setBinaryStream
84  	 */
85  	void setBlobAsBinaryStream(
86  			PreparedStatement ps, int paramIndex, InputStream contentStream, int contentLength)
87  			throws SQLException;
88  
89  	/**
90  	 * Set the given content as String on the given statement, using the given
91  	 * parameter index. Might simply invoke {@code PreparedStatement.setString}
92  	 * or create a Clob instance for it, depending on the database and driver.
93  	 * @param ps the PreparedStatement to the set the content on
94  	 * @param paramIndex the parameter index to use
95  	 * @param content the content as String, or {@code null} for SQL NULL
96  	 * @throws SQLException if thrown by JDBC methods
97  	 * @see java.sql.PreparedStatement#setBytes
98  	 */
99  	void setClobAsString(PreparedStatement ps, int paramIndex, String content)
100 			throws SQLException;
101 
102 	/**
103 	 * Set the given content as ASCII stream on the given statement, using the given
104 	 * parameter index. Might simply invoke {@code PreparedStatement.setAsciiStream}
105 	 * or create a Clob instance for it, depending on the database and driver.
106 	 * @param ps the PreparedStatement to the set the content on
107 	 * @param paramIndex the parameter index to use
108 	 * @param asciiStream the content as ASCII stream, or {@code null} for SQL NULL
109 	 * @throws SQLException if thrown by JDBC methods
110 	 * @see java.sql.PreparedStatement#setAsciiStream
111 	 */
112 	void setClobAsAsciiStream(
113 			PreparedStatement ps, int paramIndex, InputStream asciiStream, int contentLength)
114 			throws SQLException;
115 
116 	/**
117 	 * Set the given content as character stream on the given statement, using the given
118 	 * parameter index. Might simply invoke {@code PreparedStatement.setCharacterStream}
119 	 * or create a Clob instance for it, depending on the database and driver.
120 	 * @param ps the PreparedStatement to the set the content on
121 	 * @param paramIndex the parameter index to use
122 	 * @param characterStream the content as character stream, or {@code null} for SQL NULL
123 	 * @throws SQLException if thrown by JDBC methods
124 	 * @see java.sql.PreparedStatement#setCharacterStream
125 	 */
126 	void setClobAsCharacterStream(
127 			PreparedStatement ps, int paramIndex, Reader characterStream, int contentLength)
128 			throws SQLException;
129 
130 	/**
131 	 * Close this LobCreator session and free its temporarily created BLOBs and CLOBs.
132 	 * Will not need to do anything if using PreparedStatement's standard methods,
133 	 * but might be necessary to free database resources if using proprietary means.
134 	 * <p><b>NOTE</b>: Needs to be invoked after the involved PreparedStatements have
135 	 * been executed or the affected O/R mapping sessions have been flushed.
136 	 * Otherwise, the database resources for the temporary BLOBs might stay allocated.
137 	 */
138 	@Override
139 	void close();
140 
141 }